///////////////////////////////////////////////////////////////////////////////
// Copyright (c) 2009 Summit Contributors.  
// See: http://code.google.com/p/tyemill/wiki/SummitContributors
//
// The name and logo of Summit are trademarks of TYEMILL, LLC - All Rights 
// Reserved.
//
// Permission is hereby granted, free of charge, to any person obtaining a 
// copy of this software and associated documentation files (the "Software"), 
// to deal in the Software without restriction, including without 
// limitation the rights to use, copy, modify, merge, publish, distribute, 
// sublicense, and/or sell copies of the Software, and to permit persons to 
// whom the Software is furnished to do so, subject to the following 
// conditions:
//
// The above copyright notice and this permission notice shall be included 
// in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
// DEALINGS IN THE SOFTWARE.
///////////////////////////////////////////////////////////////////////////////

package summit.basecamp.helpers
{
	
import flash.net.URLRequestMethod;

import summit.basecamp.constants.BasecampOperation;
import summit.basecamp.constants.BasecampResource;
import summit.basecamp.wrappers.AbstractWrapper;
import summit.net.BasecampLoader;
import summit.net.BasecampRequest;

/**
 * Helpers for Basecamp category operations.
 */
public class CategoryHelper
{
	/** @private Constants **/
	private static const TYPE:String = BasecampResource.CATEGORY;
	private static const PATH_HELPER:String = "/categories/";
	
	/**
	 * Empty Category XML template for use with <code>create</code>.
	 */
	public static const CATEGORY_TEMPLATE:XML =
	<category>
  		<type>post</type>
  		<name/>
  		<project-id/>
	</category>;
	
	/** @private **/
	public function CategoryHelper()
	{
		
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for creating a category.
	 * 
	 * <p>Typically, the XML provided is based on the template returned from
	 * a call to <code>prepare</code>.
	 * 
	 * <p>The underlying Basecamp API requires that both <code>name</code>
	 * and <code>type</code> are specified in the provided XML. The <code>
	 * type</code> element should be filled out to be 'post' or 'attachment'.
	 * </p>
	 * 
	 * <p>Summit makes an additional requirment that the XML also contain 
	 * a <code>project-id</code> element.</p>
	 * 
	 * @param content Represents a category.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */  
	public static function create(content:XML):BasecampRequest
	{
		// POST /projects/#{project_id}/categories.xml
		var projectId:String = content.child("project-id")[0];
		
		var type:String = content.type;
		var name:String = content.name;
		
		SharedOperations.nullEmptyAssert(projectId, 
		"content does not contain a valid project-id element", true);
		
		SharedOperations.nullEmptyAssert(projectId, 
		"content does not contain a valid type element", true);
		
		SharedOperations.nullEmptyAssert(projectId, 
		"content does not contain a valid name element", true);
		
		return new BasecampRequest(
		"/projects/" + projectId + "/categories.xml", URLRequestMethod.POST,
		TYPE, BasecampOperation.CREATE, content);
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for deleting a category.
	 * 
	 * <p>Only categories without elements (elements-count == 0) can be 
	 * deleted.</p>
	 * 
	 * @param id The id of the category to be deleted.
	 *
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */
	public static function destroy(id:String):BasecampRequest
	{
		return SharedOperations.destroy(id, PATH_HELPER, TYPE);
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for getting an existing category
	 * from the store.
	 * 
	 * <p>The XML returned is pre-filled with the existing values of 
	 * the identified category, and is ready to be resubmitted via the 
	 * <code>update</code> function.</p>
	 * 
	 * @param id The id of the category to be retrieved.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */
	public static function edit(id:String):BasecampRequest
	{
		var request:BasecampRequest = SharedOperations.read(id, PATH_HELPER,
		TYPE);
		
		request.operation = BasecampOperation.EDIT;
		
		return request;
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for reading a list of categories.
	 * 
	 * <p>By default all categories in a project are listed.</p>
	 * 
	 * <p>The <code>categoryFilter</code> reduces the categories returned 
	 * to those specific to either posts or attachments.</p>
	 * 
	 * @param projectId The id of the project from which categories are to be 
	 * queried.
	 * @param categoryFilter The filter by which to reduce the list of 
	 * categories returned. By default, no filter is applied.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */
	public static function list(projectId:String, 
	categoryFilter:String = null):BasecampRequest
	{
		SharedOperations.nullEmptyAssert(projectId, "projectId");
		
		// GET /projects/#{project_id}/categories.xml(?type=[post|attachment])
		var path:String = "/projects/" + projectId + "/categories.xml";
		path = (!categoryFilter ? path : path + "?type=" + categoryFilter);
		
		return new BasecampRequest(path, URLRequestMethod.GET, TYPE, 
		BasecampOperation.LIST);
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for retrieving a template for a 
	 * new category.
	 * 
	 * <p>The template retrieved is used with <code>create</code> to 
	 * submit a new category.</p>
	 * 
	 * @param projectId The id of the project that is to be associated with 
	 * the category when submitted via a call to <code>create</code>.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */ 
	public static function prepare(projectId:String):BasecampRequest
	{
		var x:XML = new XML(CATEGORY_TEMPLATE);
		x.child("project-id")[0] = projectId;
		
		// loader knows how to handle null ops
		return new BasecampRequest(null, URLRequestMethod.GET, TYPE,
		BasecampOperation.PREPARE, x); 
	}
		
	/**
	 * Builds a <code>BasecampRequest</code> for reading a single category.
	 * 
	 * @param id The id of the category to be read.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */
	public static function read(id:String):BasecampRequest
	{
		return SharedOperations.read(id, PATH_HELPER, TYPE);
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for updating an existing 
	 * category.
	 * 
	 * <p><code>content</code> submitted to <code>update</code> is typically
	 * retrieved from <code>edit</code>.</p>
	 * 
	 * @param content The updated XML content of an existing category.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>. 
	 */ 
	public static function update(content:XML):BasecampRequest
	{
		return SharedOperations.update(content, PATH_HELPER, TYPE);	
	}
}
}
//////////////////////////////////////////////////////// gmarius@tyemill.com //